To test with Mac OS USB v1.3f3, you should have System Software v8.6 installed on an iMac, 1999 Power Macintosh G3 or 1999 PowerBook G3 Series system. Refer to the instructions presented in the "Mac OS USB DDK Readme" on how to install the software, "Installing the Mac OS USB Software". The System Software v8.6 Update is available on the Apple Software Update site.
When the system reboots, it will initially load USB, v1.2 out of the Mac OS ROM File to support USB boot devices. Later, when the file system is accessed, USB will see the updated version of Mac OS USB and reload the newer software.
This release of the DDK includes the Mac OS USB v1.3f3 release of the Extension based files. They are provided for developer to test with USB on older Power Macintosh system with third party USB PCI cards installed. Refer to the instructions presented in the "Mac OS USB DDK Readme" on how to install the software, "Installing the Mac OS USB Software".
Changes from USB v1.2 -> v1.3f3
-------------------------------
1. Added support for driver requested timeouts.
2. Implemented support in the HID driver to support vendor-specific drivers for Immersion-based force feedback joysticks.
3. Implemented support for the USB Expert to get the international strings from a USB device.
4. Provide USB suspend and resume wakeup support.
5. Fixed bug where device names were not showing up when the "not enough power" dialog was displayed.
6. USBExpertStatus calls are now re-entrant. This should solve some "missing messages" reported by some driver writers.
7. Modified USBProber to size the vertical scrollbars correctly. Fixed "flashing" problem when the expert log would overflow.
8. Added new functions allowing USB Class Drivers to get and set the Expert Status level. This will allow developers to debug specific problems they are experiencing and not overflow the log. This functionality is currently only used by USB Prober.
9. Added support for kNotifySystemSleepRevoke message.
10. Improved the performance of isochronous and interrupt transfer routines under Virtual Memory.
11. CHANGE FOR 1.3a4 from previous builds - Added support for 5-second timeout functionality for Control Endpoint only. If a device fails to transfer data for 5 seconds on the Control Endpoint (ie, NAKs continiously), then the transfer will be returned. We still permit the kUSBNo5SecTimeout flag for bulk transactions -- but we intend disallow this in a future build. -- PLEASE UPDATE YOUR DRIVERS IF YOU HAVE BEGUN TO USE THIS FLAG!
12. Fixed a problem that could permit dereferencing nil if we ran out of isoch descriptors.
13. Implemented the USBGetVersion call to obtain the version of USB present. This call is provided as an alternative for using Gestalt so that one did not need to link with InterfaceLib in order to obtain the version of USB present. The following is a sample call to demonstrate how to do this. For this example, you weak link the USBServicesLib as part of the project. The result of the call is a 4 byte 'vers' response exactly like what would be returned by using the Gestalt call with the 'usbv' selector.
#include <USB.h> // ensure that you include the USB.h v1.3 header file
UInt32 MyUSBGetVersion(void)
{
UInt32 version;
if ((Ptr) USBGetVersion != (Ptr) kUnresolvedCFragSymbolAddress)
version = USBGetVersion();
else
version = 0; // version of USB is less than 1.3
return version;
}
14. USBExpertStatus and USBExpertStatusLevel are now more efficient, if the message does not appear in the USB Prober log. USB Prober now checks the level parameter before processing the message. Before, USB Prober checked the level just before inserting the message in the log.
15. Fixed the Isochronous frStatus error codes. In USB 1.2 (and earlier) the wrong error codes were returned. For example a DataOverRun error would appear as a Stall error, and DeviceNotResponding was reported as a BitStuff error.
16. Fixed a problem with the OHCIUIM in which multiple overcurrent dialogs appeared when the root hub detected an overcurrent situation.
17. Made sure that the kNotifySystemSleepDemand messages are sent the the driver modules.
18. Fixed the Mouse driver to function better on USB CardBus-equipped PowerBooks.
19. For USB.h v1.3b3, updated the USB.h header with the correct defines for selecting timeouts when no-data is being transferred.
20. Added support for specifying timeouts when no-data is being transferred.
21. Updated the USB_API_Ref from v23 to v24v4.
22. API Addition - added the USBAddDriverForFSSpec function call. Refer to the v24v4 USB_API_Ref for a description of this call.
23. Fix out-of-order transactions that could occur on immediate errors from the UIM.
Changes from USB v1.1 -> v1.2
-------------------------------
The following changes were made for USB 1.2
1. Provides support for multiple class drivers in a single file via the extended 'cfrg' resource. The following class drivers have been merged into the "USB Device Extension" file:
USBHubDriver0
USBHubDriver1
USBCompositeDriver
USBHIDKeyboardModule
USBHIDMouseModule
USBHIDUniversalModule
USBOpenHCIDriver
2. Have enabled the isoch bit for the 'usb ' Gestalt selector to indicate support for the USBIsochRead/Write calls. If your process depends on isochronous support, check first for the presence of USB v1.2. Your installer should check for the presence of USB v1.2 and alert the user to upgrade their System Software if this release is not present.
3. Support for Control endpoints other than endpoint 0.
4. New format for the USB Expert Log. Using the version of USB Prober supplied with the DDK, you can even change the status level to hide some status messages. At the default level, typically only errors are shown in the log.
5. Hub Driver now handles hub-removal properly (should not leave any pending transactions (which could cause crashes) when hubs are unplugged.
6. Hub Driver will refuse to match to any device that's not a USB Hub.
7. Create internal interface node before initializing class drivers. This allows a driver's interfaceInitializeProc to call GetDriverConnectionID for it's interfaceRef.
8. Changed USB mouse module to always shutdown gracefully when unplugged. It could potentially hang around forever in some cases.
9. Fixed bug where the interrupt polling rate was never less than 4 ms for high-speed devices.
10. Fixed De/Allocmem to return the correct "kUSBPending" status.
11. Version Information added to "USB Device Extension".
12. New Version of USB Prober now supports PageUp/PageDown keys.
13. Fixed a USB v1.2d3 driver matching problem in the USB Expert that was mis-matching the Kodak DC 220/260 cameras to the QuickCam driver. Also the Umax scanner & Peracom serial adapter were matching to the hub driver! This problem was only in USB v1.2d3.
14. Added HID Notification method to allow all boot protocol data to be retrieved for keyboard/mouse. This new method is demonstrated in the updated driver samples for the mouse and keyboard.
15. Updated the Composite driver to indicate how much power was available in the expert log, when there was not enough power available.
16. Fixed a bug that would cause a 10 second delay if there were no USB UIMs loaded.
17. Remove USB Expert Log error message about string index = 0, this means no string is available and is not an error.
18. Fixed problem where some devices would generate a false "Not Enough Power" dialog.
19. Put manufacturer, product, and serial number string in name registry.
20. Added re-entrancy protection for all UIM calls. This should address developer-discovered problems where stressing the USB software would result in USBBulkRead returning -1 errors, or USB stopping all together.
21. Changed Keyboard & Mouse drivers to use "SetIdle" for non-Apple keyboards & mice. This should improve compatibility with some devices that fail to report key-ups except when SetIdle is used.
22. Fix USBResetPipeByReference to always allow the data-toggle to be reset in the hardware (as documented).
23. Fix usbActCount which was being returned incorrectly when it was 32k less than usbReqCount.
24. Fixed USBFatalError to once again show the Pascal-string that is passed in. We recently got it to show the string, but we were treating it as a C-string instead of the documented Pascal-string.
25. The mouse driver notification "cancel" call now clears the notificationRefCon, instead of (incorrectly) the interruptRefCon. This problem was introduced in an earlier version of USB 1.2
26. Secondary interrupts are used to serialize access to the UIM (this should have the effect of fixing random crashes with mass storage devices and scanners).
27. Fixed isoch error returns.
28. Short packets now terminate a large read request properly.
29. The last frame of an isoch write request was sometimes longer than submitted.
30. Modified USB so that only selected levels of Expert messages are displayed. By default only level 1 - 3 Expert Status messages are displayed. Messages passed using the USBExpertStatus call are level 4 messages and are not displayed unless the status level is change to 4 or 5.
31. Fixed USBIsocRead to return the correct frActCount value.
32. Fixed the incorrect error results for the USBIsocRead call that were introduced in USB v1.2f4.
Changes from USB v1.0/v1.0.1 -> v1.1
------------------------------------
The following changes were made for USB 1.1
1. USB v1.1 can support more than one USB Controller. If you are looking in the name registry, you need to look under every USB controller node for hubs and devices that may be attached.
2. Using Isochronous transfers. Version v1.1 contains support for Isochronous transfers. You can test for the presence of Isochronous support by checking the gestalt selector gestaltUSBAttr (‘usb ‘). If gestaltUSBHasIsoch (bit 1 = 0x02) is set, then Isochronous support is available in the form of two new calls:
OSStatus USBIsocWrite(USBPB *pb);
OSStatus USBIsocRead(USBPB *pb);
Refer to the Mac OS USB API Reference Guide included with this DDK for information on implementing isochronous support.
NOTE: The gestalt bit, gestaltUSBHasIsoch, was not set for versions of the 1.1 DDK before
1.1a4, even though the above mentioned calls were present. For releases of USB >= v1.1a4, this bit is set correctly.
3. USB v1.1 improves upon the bus enumeration at startup, and attempts to load drivers before other system extensions. It does this by providing task time for the USB expert to process all hub communications. When all hubs have reported that they they have discovered their devices, and we’ve searched for class drivers, then the remainder of the booting process (loading extensions and launching the finder) continues.
4. Support for System Sleep. Additional driver messages have been defined for handling sleep/wake within the MacOS. Under USB v1.1 class drivers are notified through their USBDriverNotifyProcPtr with the following messages:
kNotifyUSBSystemSleepRequest
kNotifyUSBSystemSleepDemand
These messages correspond to the SleepXXXX messages defined in the PowerManager (Inside Macintosh: Devices, chapter 6). Your driver can return any value appropriate to these messages (ie, to deny a SleepRequest, return a non-zero value).
5. Starting with USB vers 1.1a4, there is a new "locationID" property found in the name registry node of each USB device. This property contains a 32-bit number that is unique across all USB devices found in the system. It will remain the same accross reboots (and unplugs/re-plugs) for a
particular device as long as it is plugging into the same port in the USB device tree. To find the name registry entry for a particular device, you can look for the property "deviceRef" with the value equal to your deviceRef. Once you have found the NameRegistry node, you can check for
the value of the "locationID" property.
6. USBResetDevice(USBPB *PB); - A new USB function that will reset a device as specified by USBReference. If there are any outstanding USB parameter block calls on open pipes or interfaces associated with the device, these calls will complete with an error.
7. USBOpenDevice & USBConfigureInterface now kill/close interface/pipes if performed on an already open interface or device. As with USBResetDevice, if there are any outstanding USB parameter block calls on open pipes or interfaces, these calls will complete with an error.
8. Added USBToHostLong and HostToUSBLong functions.
9. USBOpenDevice now checks if the configuration requested requires more power than is available. This call returns a failure code and puts up an error dialog if there is not enough power. To keep the dialog from being displayed, make sure that the desired configuration specified in the usb.cntl.WValue field is within the power limits passed to the class driver in the Driver/InterfaceInit call.
9a. USB v1.1 catches illegal power configurations. USB raises an alert and returns an error if any driver tries to configure a device which needs more power than is available. USB provides a mechanism for the class driver to detect this problem using the USBFIndNextInterface call. The USBFIndNextInterface API is changed so that you can pass in the power available in the usbReqCount field of the USB parameter block.
10. Improved the reliability of Bulk, Interrupt, and Isochronous transfers.
11. Added "addressed" endpoint/interface functionality. Use the kUSBAddressRequest flag when passing in an endpoint/interface number. For example, when making some USBDeviceRequest calls, the WIndex field must be set to an endpoint or interface number to identify the recipient of the call. USB v1.1 simplifies the need to set this value. USB v1.1 checks if the usbFlags field has the kUSBAddressRequest bit set, and if so further checks the usb.cntl.BMRequestType field to determine what endpointNumber needs to be set in the usb.cntl.WIndex field.
12. Fixed the USBDelay call so that it now honors the kUSBTaskTimeFlag bit.
13. Fixed USBFindNextInterface to return kUSBNotFound if the specified interface does not exist.
14. Improved bus enumeration so that most USB devices which are present at system startup will be enumerated before INITs are executed.
15. Changed the method by which Mac OS USB reads the device descriptor to use the method defined in the USB 1.1 specification. This means that the first 8 bytes of the descriptor are read, then the entire descriptor is read.
16. Implemented "Captive device" support. This provides a fix for some compound devices that have 4 built-in ports and a captive device (ie. a keyboard with a built in hub that has 4 ports). This is per the USB 1.1 specification (not the Apple Mac OS v.1.1 spec).
17. Fixed a problem where some 3rd party keyboards didn't set the LEDs correctly, or 3rd party mice did not work correctly.
18. Updated USBProber - Fixed a problem where incorrect ProbeEndPoint messages were sometimes seen. USBProber now displays (again) the root hub info.
19. The root hub driver was updated and the product ID has changed. As a reminder, you should never 1. talk to the root hub directly, 2. replace the hub drivers, and 3. depend on the root hub product ID staying the same from release to release.
20. Fixed USBGetNextDeviceByClass so that it correctly iterates through all devices present, including Composite class devices.
21. DeviceNotifications are sent for matching devices already connected when the USBInstallDeviceNotification call is made. When a client registers to receive device notifications, any existing devices are reported immediately.
22. Fixed bug that caused immediate errors to be returned incorrectly. This causes problems when drivers requested transfer that could not be accomodated, they would never get a callback indicating the transfer completed.
23. Implemented Composite class driver replacement, to allow vendor-specific composite drivers to be re-loaded if attached at boot. This change makes all devices attached at boot look like they have been hot plugged.
24. Added capability for more than one driver to be tried for a given device. Now drivers can return an error from the validateHWProc and USB will search for another driver match.
25. Fixed problem that produced "pipeStalled" errors after devices had been unplugged/replugged 15 times or so.
26. Fixed a problem where if a mouse were removed while it's button was down, the system would be frozen and could not recover.
27. Fixed a bug that caused more than one mouse attached to an iMac to get a "sticky" button sometimes.
28. Improved hub hot plug/unplug robustness.
29. Fixed problem that prevented "perfect" match when deviceRevision match was exact.
30. Fixed USBGetDeviceDescriptor to return the correct descriptor length value.
31. Fixed DeviceNotification to identify whether an interface or device driver is being added.
32. Fixed problem that was making the mouse non-functional after quiting from Quake game.
33. Fixed problem where high-powered devices (such as QuickCam) would not report insufficient power when connected to a bus-powered hub. Now they do!
34. Fixed problem that would freeze the mouse when unplugging the keyboard while any Office98 app was running.
35. Fixed problem where a USB class driver could receive two callbacks when an error occurred, and they attempted to abort any other transactions.
API Changes from USB v1.0/v1.0.1 -> v1.1
----------------------------------------
The following API changes were made for v1.1 and WILL affect the compilation of your program.
1. The USBPB structure has been changed to support Isochronous parameter blocks. The USB Parameter Block (USBPB) has been converted into a unions to support Isochronous transfers. The change is binary compatible with previous USB releases (can keep the same kUSBCurrentVersion value), however you will need to modify your source code in order to use the USB.h header file that is supplied with the Mac OS USB v1.1 DDK.
The update can typically be made with a search/replace of the following strings:
Old New
usbBMRequestType usb.cntl.BMRequestType
usbBRequest usb.cntl.BRequest
usbWValue usb.cntl.WValue
usbWIndex usb.cntl.WIndex
To aid in this conversion, macros with these substitutions are available in USB.h, just define OLDUSBNAMES before including <USB.h> We recommend changing your source code soon as possible, as these macros will disappear in the future.
2. There has been a change to the USBClassDriverPluginDispatchTable. The USBDDriverNotifyProcPtr is prototyped as
If the version of the USBClassDriverPluginDispatchTable is set to kUSBClassDriverPluginVersion, (used from the v1.1 USB.h header file) then the USBDriverNotifyProcPtr has the prototype described above. Note that drivers that were compiled with an earlier version of the USB.h header file will have a different kUSBClassDriverPluginVersion value and the USB Manager will call the DriverNotifyProc without the refcon parameter.
USB 1.1 Compatibility with USB 1.0.1
------------------------------------
You can build your USB compatible products using the USB v1.1 components and run them under a USB v1.0 or v1.0.1 environment so long as you follow these caveats -
1. When your USBDriverNotifyProcPtr routine is called, check the version of USB that is present before using the refcon parameter. For USB v1.0 and v1.0.1, the refcon parameter is invalid.
2. For all versions of USB, check that there is isochronous support before making the USBIsochRead/Write calls. Your class driver must also weak link with the USBServicesLib file. If the driver makes the USBIsocRead/Write calls and hard links with the USBServicesLib file, then the system will check for the support of these calls, find that they are not available and not allow the driver to load.
3. Keep in mind that for v1.0 and v1.0.1, there are known problems which are not fixed simply by building the product with the USB v1.1 headers and libraries. These problems are referenced in this readme file. Some of these issues are discussed in more detail on the USB Developer Alerts web page. The URL to this page is as follows:
1. Implemented a fix to the USBModem example, file ShimSerialHAL.c, HAL_ShimInput routine to correctly handle incoming parameter block data processing.
Changes from USB v1.0 -> v1.0.1
-------------------------------
The following changes were made for USB 1.0.1
1. USB.h
- Removed the call USBGetConnectionIDByClass as its usefulness is limited. Use the USBGetNextDeviceByClass call instead so that you can interate through the available devices.
- Added a number of Hub Defines that were previously in a private interface file.
2. Addressed the following bugs
- Fixed several USBBulkRead issues which includes the lost print band problem.
- UIM buffer alignment fix. The UIM (USBOpenHCIDriver) could cause a class driver to receive a -6908 error if the buffer passed in was not aligned on a "MaxPacketSized" boundary. We have sent out information on how to workaround this to developers, this fix will remove this restriction. This problem can only occur when reading from BULK devices.
- Device stall could return improper value in the usbActCount field. This could make it impossible for drivers to attempt to recover from a pipe stall error.
- Workaround for potential data corruption with some OHCI controllers. This problem shows up as corruption in transmitted high-speed data, following a low-speed input data transfer.
- Fixed problem with USB Services replacement that causes a crash after the "No Software" dialog is displayed in the case where there is a "USBFamilyExpert" extension in the system folder.
-
Hub attach delay. We now wait, as per the USB Specification, the required 100ms after a new device is attached to the hub before configuring it. This should improve hot-plugging of devices (especially if sometimes they aren't detected).
- Improved driver matching for compatibility shims. The shims were matching on info from the driver, not info from the device. This could cause some drivers not to be found by a shim.
- Make sure ClassDrivers are locked to prevent VirtualMemory paging. This could potentially fix crashing problems on very busy systems.
- Increased idle-queue size to 96. We could potentially overflow this queue (and have things stop working) if there were too many devices attached.
- Fixed several incorrect error returns in the PipeState functions.
- Fixed problem where a legal minimum config descriptor (a single configuration and interface) cause and error when attempting to find the interface.
- Zero length transactions are allowed on the bus.
- USL and UIM have to agree on a version number to work together. This stops unmatched interfaces causing problems.
Changes/Additions to the USB v1.0.1 DDK
---------------------------------------
1. Include the correct UniversalHIDModule class driver for use with Game Sprockets v1.3. Game Sprocket supported devices now work properly on systems which use the Extension-based USB.
2. Updated the PrinterClassSample so that the it fixes the 68K structure alignment problem. Also modified the code so that the DRVR and NameRegistry items are removed, when the class module unloads.
